om2: MetricFamilyName is MetricName #2791

bwplotka · 2025-12-03T10:38:51Z

~~We can either merge this with TODOs before complex values/types or wait for complex type/values.~~

bwplotka · 2025-12-03T10:46:06Z

I am bit surprised but I couldn't find any special rule for those suffixes in the ABNF to change... also tests passes despite me adding suffixes to MF names. Something smells like ABNF is too relaxed.

ArthurSens

I could review only half of the PR 😬, I have some small comments

docs/specs/om/open_metrics_spec_2_0.md

ArthurSens · 2025-12-03T13:45:52Z

docs/specs/om/open_metrics_spec_2_0.md

-The name of a MetricFamily MUST NOT result in a potential clash for sample metric names as per the ABNF with another MetricFamily in the Text Format within a MetricSet. An example would be a gauge called "foo_total" as a counter called "foo" could create a "foo_total" in the text format.
+Names SHOULD be in snake_case. Names SHOULD follow the restrictions in the ABNF section under `metricname`. Metric names MAY be any quoted and escaped UTF-8 string as described in the ABNF section. Be aware that exposing UTF-8 metrics is still experimental and may reduce usability, especially when `_total` or unit suffixes are not included.
+
+Colons in MetricFamily names are RESERVED to signal that the MetricFamily is the result of a calculation or aggregation of a general purpose monitoring system.


I don't know if this holds any value in the spec. When we mention 'RESERVED', are we instructing SDKs not to allow colons?

I also don't know what RESERVED means? I don't think it is one of the keywords (like MUST, SHOULD, MUST NOT).

I think we can say "MUST NOT be used unless ..."

I will keep RESERVED as it was there before my change. We use RESERVED word 6 times already in this document, so let's have a dedicated PR to change it.

I think it's fine, but to be strict with https://datatracker.ietf.org/doc/html/rfc2119 we could check MUST NOT.

Let's focus on suffixes in this PR, WDYT?

thats also fine by me

docs/specs/om/open_metrics_spec_2_0.md

ywwg · 2026-02-09T20:18:00Z

do we still intend to merge this?

bwplotka · 2026-02-10T06:59:23Z

I think so. Much simpler now with Composite Types merged in.

bwplotka · 2026-02-10T06:59:33Z

PTAL @krajorama @dashpole @ywwg

bwplotka · 2026-02-10T06:59:47Z

docs/specs/om/open_metrics_spec_2_0.md


 * [Histogram](#histogram) MetricFamily Type.
-* [GaugeHistogram](#gauge-histogram) MetricFamily Type.
+* [GaugeHistogram](#gaugehistogram) MetricFamily Type.


FYI: Broken link

bwplotka · 2026-02-10T07:01:00Z

docs/specs/om/open_metrics_spec_2_0.md

+or dropped data.

-The name of a MetricFamily MUST NOT result in a potential clash for sample metric names as per the ABNF with another MetricFamily in the Text Format within a MetricSet. An example would be a gauge called "foo_total" as a counter called "foo" could create a "foo_total" in the text format.
+Exposers MUST avoid names that could conflict with the Text OpenMetrics 1.0 [histogram](https://github.com/prometheus/docs/blob/main/docs/specs/om/open_metrics_spec.md#histogram-1), [gaugehistogram](https://github.com/prometheus/docs/blob/main/docs/specs/om/open_metrics_spec.md#gaugehistogram-1) and [summary](https://github.com/prometheus/docs/blob/main/docs/specs/om/open_metrics_spec.md#summary-1) suffixes.


Another way to put it is that gauges, counters, stateset names MUST NOT end with _count, _sum, _gcount, _gsum, _bucket - kind of simple rule. Would that be more clear?

I'd just simplify further:

MetricFamily name MUST NOT end with _count, _sum, _gcount, _gsum, _bucket.

It's true for anything except Histograms and Gauge Histograms , including Summary since that has series without magic suffixes. But I don't think it's worth making an exception for Histograms, Gauge Histograms. Especially because I don't think people will actually follow this unless SDKs prohibit it and I think we need to add a line about ingestors:

Ingestors MAY accept non compliant MetricFamily names and only error out when a naming clash occurs.

Generally good point, but especially _count might be common as a standalone gauge or even counter. This line would prohibit for compatibility reason (so tmp time) and actually is not needed if the same target does NOT expose <metric without _count_but_histogram>.

Ingestors MAY accept non compliant MetricFamily names and only error out when a naming clash occurs.

Again, if this needs to be stronger that we need to move MetricFamily name MUST NOT end with _count, _sum, _gcount, _gsum, _bucket. to SHOULD NOT.

Every "must" MAY be accepted by some implementations, no?

I proposed SHOULD NOT for wide rule, and MUST NOT for collision explanation - framed as "OpenMetrics 2 converted to OpenMetrics 1 or Prom TEXT should not cause collisions)

Yeah, I agree with SHOULD NOT. MUST NOT presumably means that we place more of a burden on clients exposing the metrics to ensure it doesn't happen (like suffixes in OM 1.0). We either would fail scrapes with bad suffixes, or we would have to "fix" names by modifying them to make them valid (which we sometimes did for OM 1.0).

krajorama · 2026-02-10T08:50:48Z

docs/specs/om/open_metrics_spec_2_0.md

+or dropped data.

-The name of a MetricFamily MUST NOT result in a potential clash for sample metric names as per the ABNF with another MetricFamily in the Text Format within a MetricSet. An example would be a gauge called "foo_total" as a counter called "foo" could create a "foo_total" in the text format.
+Exposers MUST avoid names that could conflict with the Text OpenMetrics 1.0 [histogram](https://github.com/prometheus/docs/blob/main/docs/specs/om/open_metrics_spec.md#histogram-1), [gaugehistogram](https://github.com/prometheus/docs/blob/main/docs/specs/om/open_metrics_spec.md#gaugehistogram-1) and [summary](https://github.com/prometheus/docs/blob/main/docs/specs/om/open_metrics_spec.md#summary-1) suffixes.


I'd just simplify further:

MetricFamily name MUST NOT end with _count, _sum, _gcount, _gsum, _bucket.

It's true for anything except Histograms and Gauge Histograms , including Summary since that has series without magic suffixes. But I don't think it's worth making an exception for Histograms, Gauge Histograms. Especially because I don't think people will actually follow this unless SDKs prohibit it and I think we need to add a line about ingestors:

Ingestors MAY accept non compliant MetricFamily names and only error out when a naming clash occurs.

docs/specs/om/open_metrics_spec_2_0.md

Fixes prometheus/OpenMetrics#305 Signed-off-by: bwplotka <bwplotka@gmail.com>

ywwg · 2026-02-10T16:10:43Z

docs/specs/om/open_metrics_spec_2_0.md


-The name of a MetricFamily MUST NOT result in a potential clash for sample metric names as per the ABNF with another MetricFamily in the Text Format within a MetricSet. An example would be a gauge called "foo_total" as a counter called "foo" could create a "foo_total" in the text format.
+MetricFamily name SHOULD NOT end with `_count`, `_sum`, `_gcount`, `_gsum`, `_bucket`. Specifically name MUST NOT create 
+MetricName collision when converted to [the Text OpenMetrics 1.0](https://prometheus.io/docs/specs/om/open_metrics_spec).


nit - are we manually word-wrapping or no? Other paragraphs seem not to have newlines mid-paragraph. The markdown format doesn't care but we might as well be consistent.

We don't need to, will revert. We could use autoformatter too to remove those if we want

ywwg · 2026-02-10T16:12:14Z

docs/specs/om/open_metrics_spec_2_0.md

+###### Reserved Suffixes

-The name of a MetricFamily MUST NOT result in a potential clash for sample metric names as per the ABNF with another MetricFamily in the Text Format within a MetricSet. An example would be a gauge called "foo_total" as a counter called "foo" could create a "foo_total" in the text format.
+MetricFamily name SHOULD NOT end with `_count`, `_sum`, `_gcount`, `_gsum`, `_bucket`. Specifically name MUST NOT create 


Suggested change

MetricFamily name SHOULD NOT end with `_count`, `_sum`, `_gcount`, `_gsum`, `_bucket`. Specifically name MUST NOT create

MetricFamily name SHOULD NOT end with `_count`, `_sum`, `_gcount`, `_gsum`, `_bucket`. Specifically a name MUST NOT create a MetricName collision when converted to [the Text OpenMetrics 1.0](https://prometheus.io/docs/specs/om/open_metrics_spec).

ywwg · 2026-02-10T16:12:48Z

docs/specs/om/open_metrics_spec_2_0.md

-* Gauge: `` (empty)
-* StateSet: `` (empty)
-* Unknown: `` (empty)
+> This rule is because this specification is following a shift in Prometheus ecosystem towards [composite values](#compositevalues) instead of [the "classic" representation](https://prometheus.io/docs/specs/om/open_metrics_spec/#histogram-1). However, this transformation will take time.


Suggested change

> This rule is because this specification is following a shift in Prometheus ecosystem towards [composite values](#compositevalues) instead of [the "classic" representation](https://prometheus.io/docs/specs/om/open_metrics_spec/#histogram-1). However, this transformation will take time.

> This rule exists because this specification is following a shift in Prometheus ecosystem towards [composite values](#compositevalues) instead of [the "classic" representation](https://prometheus.io/docs/specs/om/open_metrics_spec/#histogram-1). However, this transformation will take time.

ywwg · 2026-02-10T16:14:16Z

docs/specs/om/open_metrics_spec_2_0.md

+A non-compliant example would be a gauge called `foo_bucket` and a histogram called `foo`. Exposers negotiating the older
+OpenMetrics or Text formats, or ingestors which support only the older data model could end up storing `foo` histogram 
+in a classic representation (`foo_bucket`, `foo_count`, `foo_sum`) causing clash with the gauge and scrape rejection or dropped data.


Suggested change

A non-compliant example would be a gauge called `foo_bucket` and a histogram called `foo`. Exposers negotiating the older

OpenMetrics or Text formats, or ingestors which support only the older data model could end up storing `foo` histogram

in a classic representation (`foo_bucket`, `foo_count`, `foo_sum`) causing clash with the gauge and scrape rejection or dropped data.

A non-compliant example would be a gauge called `foo_bucket` and a histogram called `foo`. Exposers negotiating the older OpenMetrics or Text formats, or ingestors which support only the older data model could end up storing the `foo` histogram in the classic representation (`foo_bucket`, `foo_count`, `foo_sum`), which would clash with the gauge and cause a scrape rejection or dropped data.

bwplotka requested review from ArthurSens, dashpole, krajorama and ywwg December 3, 2025 10:38

ArthurSens reviewed Dec 3, 2025

View reviewed changes

bwplotka commented Dec 3, 2025

View reviewed changes

docs/specs/om/open_metrics_spec_2_0.md Show resolved Hide resolved

bwplotka commented Dec 3, 2025

View reviewed changes

docs/specs/om/open_metrics_spec_2_0.md Outdated Show resolved Hide resolved

bwplotka commented Dec 3, 2025

View reviewed changes

docs/specs/om/open_metrics_spec_2_0.md Outdated Show resolved Hide resolved

bwplotka commented Dec 3, 2025

View reviewed changes

docs/specs/om/open_metrics_spec_2_0.md Outdated Show resolved Hide resolved

dashpole reviewed Dec 3, 2025

View reviewed changes

docs/specs/om/open_metrics_spec_2_0.md Outdated Show resolved Hide resolved

jan--f added the kind/feature New documentation content label Dec 5, 2025

bwplotka force-pushed the bwplotka/om2-restr branch 6 times, most recently from 11a31fa to ff36b8d Compare February 10, 2026 06:41

bwplotka commented Feb 10, 2026

View reviewed changes

krajorama reviewed Feb 10, 2026

View reviewed changes

om2: MetricFamilyName is MetricName

70aa8d3

Fixes prometheus/OpenMetrics#305 Signed-off-by: bwplotka <bwplotka@gmail.com>

bwplotka force-pushed the bwplotka/om2-restr branch from ff36b8d to 70aa8d3 Compare February 10, 2026 09:06

dashpole approved these changes Feb 10, 2026

View reviewed changes

ywwg reviewed Feb 10, 2026

View reviewed changes

	MetricFamily name SHOULD NOT end with `_count`, `_sum`, `_gcount`, `_gsum`, `_bucket`. Specifically name MUST NOT create
	MetricFamily name SHOULD NOT end with `_count`, `_sum`, `_gcount`, `_gsum`, `_bucket`. Specifically a name MUST NOT create a MetricName collision when converted to [the Text OpenMetrics 1.0](https://prometheus.io/docs/specs/om/open_metrics_spec).

	> This rule is because this specification is following a shift in Prometheus ecosystem towards [composite values](#compositevalues) instead of [the "classic" representation](https://prometheus.io/docs/specs/om/open_metrics_spec/#histogram-1). However, this transformation will take time.
	> This rule exists because this specification is following a shift in Prometheus ecosystem towards [composite values](#compositevalues) instead of [the "classic" representation](https://prometheus.io/docs/specs/om/open_metrics_spec/#histogram-1). However, this transformation will take time.

om2: MetricFamilyName is MetricName #2791

Are you sure you want to change the base?

om2: MetricFamilyName is MetricName #2791

Uh oh!

Conversation

bwplotka commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bwplotka commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ArthurSens left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ywwg commented Feb 9, 2026

Uh oh!

bwplotka commented Feb 10, 2026

Uh oh!

bwplotka commented Feb 10, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bwplotka Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

bwplotka commented Dec 3, 2025 •

edited

Loading

bwplotka commented Dec 3, 2025 •

edited

Loading

bwplotka Feb 10, 2026 •

edited

Loading